<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
<topic id="topic1">
  <title id="by20941">CREATE RESOURCE GROUP</title>
  <body>
    <p id="sql_command_desc">Defines a new resource group.</p>
    <section id="section2">
      <title>Synopsis</title>
      <codeblock id="sql_command_synopsis">CREATE RESOURCE GROUP <varname>name</varname> WITH (<varname>group_attribute</varname>=<varname>value</varname> [, ... ])</codeblock>
      <p>where <varname>group_attribute</varname> is:</p>
      <codeblock>CPU_RATE_LIMIT=<varname>integer</varname> | CPUSET=<varname>tuple</varname>
[ MEMORY_LIMIT=<varname>integer</varname> ]
[ CONCURRENCY=<varname>integer</varname> ]
[ MEMORY_SHARED_QUOTA=<varname>integer</varname> ]
[ MEMORY_SPILL_RATIO=<varname>integer</varname> ]
[ MEMORY_AUDITOR= {vmtracker | cgroup} ]</codeblock>
    </section>
    <section id="section3">
      <title>Description</title>
      <p>Creates a new resource group for Greenplum Database resource management. You can create resource groups to manage resources for roles or 
        to manage the resources of a Greenplum Database external component such as PL/Container.</p>
       <p>A resource
         group that you create to manage a user role identifies concurrent transaction, memory,
         and CPU limits for the role when resource groups are enabled. You may assign such resource groups to one or more roles.</p>
      <p>A resource group that you create to manage the resources of a Greenplum Database external component such as PL/Container identifies the memory and CPU limits for the component when resource groups are enabled. These resource groups use cgroups for both CPU and memory management. Assignment of resource groups to external components is component-specific. For example, you assign a PL/Container resource group when you configure a PL/Container runtime. You cannot assign a resource group that you create for external components to a role, nor can you assign a resource group that you create for roles to an external component.</p>
      <p>You must have <codeph>SUPERUSER</codeph> privileges to create a resource group. The maximum number of resource groups allowed in your Greenplum Database cluster is 100.</p>
      <p>Greenplum Database pre-defines two default resource groups: <codeph>admin_group</codeph>
         and <codeph>default_group</codeph>. These group names, as well as the group name <codeph>none</codeph>, are reserved.</p>
      <p>
        To set appropriate limits for resource groups, the Greenplum Database administrator must
        be familiar with the queries typically run on the system, as well as the users/roles running those queries and the external components they may be using, such as PL/Containers.</p>
      <p>
        After creating a resource group for a role, assign the group to one or more roles using the <codeph><xref
            href="ALTER_ROLE.xml#topic1" type="topic" format="dita"/></codeph> or <codeph><xref
            href="./CREATE_ROLE.xml#topic1" type="topic" format="dita"/></codeph> commands.</p>
      <p>
        After you create a resource group to manage the CPU and memory resources of an external component, configure the external component to use the resource group. For example, configure the PL/Container runtime <codeph>resource_group_id</codeph>.</p>
    </section>
    <section id="section4">
      <title>Parameters</title>
      <parml>
        <plentry>
          <pt>
            <varname>name</varname>
          </pt>
          <pd>The name of the resource group.</pd>
        </plentry>
        <plentry>
          <pt>CONCURRENCY <varname>integer</varname></pt>
          <pd>The maximum number of concurrent transactions, including active and idle transactions, that are permitted for this resource group. The <codeph>CONCURRENCY</codeph> value must be an integer in the range [0 .. <codeph>max_connections</codeph>]. The default <codeph>CONCURRENCY</codeph> value  for resource groups defined for roles is 20.</pd>
          <pd>You must set <codeph>CONCURRENCY</codeph> to zero (0) for resource groups that you create for external components.</pd>
          <pd><note>You cannot set the <codeph>CONCURRENCY</codeph> value for the <codeph>admin_group</codeph> to zero (0).</note></pd>
        </plentry>
        <plentry>
          <pt>CPU_RATE_LIMIT <varname>integer</varname></pt>
          <pt>CPUSET <varname>tuple</varname></pt>
          <pd>Required. You must specify only one of <codeph>CPU_RATE_LIMIT</codeph> or <codeph>CPUSET</codeph> when you create a resource group.</pd>
          <pd><codeph>CPU_RATE_LIMIT</codeph> is the percentage of CPU resources to allocate to this resource group. The minimum CPU percentage you can specify for a resource group is 1. The maximum is 100. The sum of the <codeph>CPU_RATE_LIMIT</codeph> values specified for all resource groups defined in the Greenplum Database cluster must be less than or equal to 100.
          </pd>
          <pd><codeph>CPUSET</codeph> identifies the CPU cores to reserve for this resource group. The CPU cores that you specify in <varname>tuple</varname> must be available in the system and cannot overlap with any CPU cores that you specify for other resource groups.</pd><pd><varname>tuple</varname> is a comma-separated list of single core numbers or core number intervals. You must enclose <varname>tuple</varname> in single quotes, for example, '1,3-4'.</pd><pd><note>You can configure <codeph>CPUSET</codeph> for a resource group only after you have enabled resource group-based resource management for your Greenplum Database cluster.</note>
          </pd>
        </plentry>
        <plentry>
          <pt>MEMORY_LIMIT <varname>integer</varname></pt>
          <pd>The total percentage of Greenplum Database memory resources to reserve for this
            resource group. The minimum memory percentage you can specify for a resource
            group is 0. The maximum is 100. The default value is 0.</pd>
          <pd>When you specify a <codeph>MEMORY_LIMIT</codeph> of 0, Greenplum Database
            reserves no memory for the resource group, but uses global shared memory to
            fulfill all memory requests in the group. If <codeph>MEMORY_LIMIT</codeph> is 0,
           <codeph>MEMORY_SPILL_RATIO</codeph> must also be 0.</pd>
          <pd>The sum of the <codeph>MEMORY_LIMIT</codeph> values specified for all resource groups defined in the Greenplum Database cluster must be less than or equal to 100.</pd>
        </plentry>
        <plentry>
          <pt>MEMORY_SHARED_QUOTA <varname>integer</varname></pt>
          <pd>The quota of shared memory in the resource group. Resource groups with a <codeph>MEMORY_SHARED_QUOTA</codeph> threshold set aside a percentage of memory allotted to the resource group to share across transactions. This shared memory is allocated on a first-come, first-served basis as available. A transaction may use none, some, or all of this memory. The minimum memory shared quota percentage you can specify for a resource group is 0. The maximum is 100. The default <codeph>MEMORY_SHARED_QUOTA</codeph> value is 80.</pd>
        </plentry>
        <plentry>
          <pt>MEMORY_SPILL_RATIO <varname>integer</varname></pt>
          <pd>The memory usage threshold for memory-intensive operators in a transaction.
            When this threshold is reached, a transaction spills to disk. You can specify
            an integer percentage value  from 0 to 100 inclusive. The default
            <codeph>MEMORY_SPILL_RATIO</codeph> value is 0. When <codeph>MEMORY_SPILL_RATIO</codeph>
            is 0, Greenplum Database uses the
            <xref href="../config_params/guc-list.xml#statement_mem" format="dita"><codeph>statement_mem</codeph></xref>
            server configuration parameter value to control initial query operator memory.</pd>
        </plentry>
        <plentry>
          <pt>MEMORY_AUDITOR {vmtracker | cgroup}</pt>
          <pd>The memory auditor for the resource group. Greenplum Database employs virtual memory
            tracking for role resources and cgroup memory tracking for resources used by external
            components. The default <codeph>MEMORY_AUDITOR</codeph> is <codeph>vmtracker</codeph>.
            When you create a resource group with <codeph>vmtracker</codeph> memory auditing,
            Greenplum Database tracks that resource group's memory internally.</pd>
          <pd>When you create a resource group specifying the <codeph>cgroup</codeph>
            <codeph>MEMORY_AUDITOR</codeph>, Greenplum Database defers the accounting of memory used
            by that resource group to cgroups. <codeph>CONCURRENCY</codeph> must be zero (0) for a
            resource group that you create for external components such as PL/Container. You cannot
            assign a resource group that you create for external components to a Greenplum Database
            role.</pd>
        </plentry>
      </parml>
    </section>
    <section id="section5"><title>Notes</title>
        <p>You cannot submit a <codeph>CREATE RESOURCE GROUP</codeph> command in an explicit transaction or sub-transaction.</p>
        <p>Use the
          <codeph>gp_toolkit.gp_resgroup_config</codeph> system view to display the limit 
        settings of all resource groups:</p><codeblock>SELECT * FROM gp_toolkit.gp_resgroup_config;</codeblock>
    </section>
    <section id="section6">
      <title>Examples</title>
      <p>Create a resource group with CPU and memory limit percentages of 35: </p>
      <codeblock>CREATE RESOURCE GROUP rgroup1 WITH (CPU_RATE_LIMIT=35, MEMORY_LIMIT=35);</codeblock>
      <p>Create a resource group with a concurrent transaction limit of 20, a memory limit of 15, and a CPU limit of 25:</p>
      <codeblock>CREATE RESOURCE GROUP rgroup2 WITH (CONCURRENCY=20, 
  MEMORY_LIMIT=15, CPU_RATE_LIMIT=25);</codeblock>
      <p>Create a resource group to manage PL/Container resources specifying a memory limit of 10, and a CPU limit of 10:</p>
      <codeblock>CREATE RESOURCE GROUP plc_run1 WITH (MEMORY_LIMIT=10, CPU_RATE_LIMIT=10,
  CONCURRENCY=0, MEMORY_AUDITOR=cgroup);</codeblock>
      <p>Create a resource group with a memory limit percentage of 11 to which you assign CPU cores 1 to 3:</p>
      <codeblock>CREATE RESOURCE GROUP rgroup3 WITH (CPUSET='1-3', MEMORY_LIMIT=11);</codeblock>
    </section>
    <section id="section7">
      <title>Compatibility</title>
      <p><codeph>CREATE RESOURCE GROUP</codeph> is a Greenplum Database extension. There is no
        provision for resource groups or resource management in the SQL standard.</p>
    </section>
    <section id="section8">
      <title>See Also</title>
      <p><codeph><xref href="ALTER_ROLE.xml#topic1" type="topic" format="dita"/></codeph>,
            <codeph><xref href="./CREATE_ROLE.xml#topic1" type="topic" format="dita"/></codeph>,
            <codeph><xref href="ALTER_RESOURCE_GROUP.xml#topic1" type="topic" format="dita"
          /></codeph>, <codeph><xref href="./DROP_RESOURCE_GROUP.xml#topic1" type="topic"
            format="dita"/></codeph></p>
    </section>
  </body>
</topic>
